/*
 ************************************************************************************
 * Copyright (C) 2001-2011 encuestame: system online surveys Copyright (C) 2011
 * encuestame Development Team.
 * Licensed under the Apache Software License version 2.0
 * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to  in writing,  software  distributed
 * under the License is distributed  on  an  "AS IS"  BASIS,  WITHOUT  WARRANTIES  OR
 * CONDITIONS OF ANY KIND, either  express  or  implied.  See  the  License  for  the
 * specific language governing permissions and limitations under the License.
 ************************************************************************************
 */
package org.encuestame.utils.oauth;

/**
 * Models an active OAuth handshake that, when completed,
 * results in a connection being established between a client application and a user account.
 * @author Picado, Juan juanATencuestame.org
 * @since Dec 24, 2010 3:55:45 PM
 * @version $Id:$
 */
public interface OAuthSession {

    /**
     * The api key that identifies the client application.
     */
    String getApiKey();

    /**
     * The URL the client application wants the server to redirect the member to after he or she authorizes the connection.
     */
    String getCallbackUrl();

    /**
     * The OAuthSession or request key.  Uniquely identifies this OAuthSession object.
     * Presented by the client application for each step of the connection process.
     */
    String getRequestToken();

    /**
     * The request token secret.
     * Used for signature verification for requests made by the client during the connection process.
     * OAuth 1.0 only.
     */
    String getSecret();

    /**
     * Flag that indicates if a member has authorized the connection yet.
     * Initially false.  True once the user clicks "Yes, I allow application identified by apiKey to access my data".
     */
    boolean authorized();

    /**
     * The id of the member account that authorized the app connection.
     * Returns null until {@link #authorized()} returns true.
     */
    Long getAuthorizingAccountId();

    /**
     * The verifier generated by the OAuthProvider upon user authorization.
     * Expected to be submitted to the client on the accessToken request that follows the authorization callback.
     * Returns null until {@link #authorized()} returns true.
     * OAuth 1.0 only.
     */
    String getVerifier();

}
